<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title>Help for the HyperAddin</title>
</head>
<body>
    <h2>
        Help for the HyperAddin</h2>
    <h3>
        Motivation</h3>
    <p>
        Developer's should comment their code more.&nbsp; However I have noticed that comments
        alone are not enough.&nbsp; You need to be able to FIND the relevant comments at
        the time you need them. &nbsp; It is reasonably common that related pieces of code
        are lexically far from on another so you
        might not find the comments you are interested in at the time you need them. &nbsp;&nbsp;
        One manifestation of this is that there is often no good place to put an 'overview' comment so that readers can find it. &nbsp; The first step in encouraging people to write
        good comments in their code is to increase the value of those comments by 'channeling'
        people who should be reading it to comments most relevant to them.
    </p>
    <p>
        This is where the Visual Studio HyperAddin comes in.&nbsp; Visual Studio already
        had the ability to recognize and quickly navigate (with Ctrl LeftClick) to URLs
        embedded in the comments of the code.&nbsp; This is great, but what is really needed
        is a way of referring quickly and easily from one part of the code to part of the
        code (or
        to architectural documents checked in with the code). &nbsp; That is exactly what
        the HyperAddin does:&nbsp; It makes creating and following hyper-links in your code
        trivial. &nbsp; Now you only have to explain something once in a comment and refer
        to it many times (got lots of overloaded methods?&nbsp; They should all refer to
        the 'master' that does the real work). &nbsp;
    </p>
    <p>
        Another related feature is the 'GoOut' command that takes you to the enclosing structure
        (either method, class, or file).&nbsp; These are great places to put 'overview'
        comments and cross links to other subsystems. &nbsp;&nbsp; With a few such links
        you get a richly interconnected graph of comments that let people navigate to where
        they want (kind of like the web).&nbsp;
    </p>
    <p>
        The other feature of HyperAddin is related to comments too. &nbsp;
        When you start writing comments that are many lines long, you find that what you
        really want your editor to word wrap.&nbsp; The HyperAddin does this for you too.
        &nbsp; But even
        that is not enough.&nbsp; You want your comments to be more like a word processor,
        with bulleted lists, and smart indenting. &nbsp; While we can't make a ASCII file
        into a full fledged word processor, Hyperlink does its best with a few simple conventions.</p>
    <p>
        &nbsp;In short the HyperAddin tries to take some of the pain out of writing more
        comments for your code.&nbsp; &nbsp; &nbsp;
    </p>
    <h3>
        Feature Overview.</h3>
    <p>
        The main features of the HyperAddin are &nbsp;
    </p>
    <ul>
        <li><a href="#CodeHyperlinking">Anchors and Hyerlinks in your code comments.</a> &nbsp;
            Quickly navigate to related parts of your code by simply clicking on a hyperlink
            in your comments. </li>
        <li><a href="#GoOut">'GoOut' Navigation. </a>&nbsp; Quickly find the method, class,
            and top of the file of the method you are currently in.&nbsp; These places are where
            you should be put &nbsp;interesting comments about the 'big picture' comments about
            the design of the
            code.&nbsp; </li>
        <li><a href="#FormattingComments">Word wrapping in comments</a>.&nbsp; Form nicely justified
            paragraphs in your comments with one click of the mouse.&nbsp; </li>
        <li>Supports both C#, C++, JScript and VB style comments.&nbsp; </li>
    </ul>
    <p>
        These features manifest themselves in two user interface elements</p>
    <ul>
        <li>The <strong>'Addin' menu item</strong> on the main menu bar. &nbsp;&nbsp; You will
            see at the end of the main menu bar (to the right of the 'Help' menu item), the
            'Addin' menu item.&nbsp; This item begins a hierarchy which exposes <strong>all</strong>
            of the commands that the addin provides.&nbsp; </li>
        <li>The <strong>Addin toolbar</strong>.&nbsp; &nbsp; This toolbar has the most commonly
            used commands for the addin. &nbsp;Like all Visual Studio command bars, more commands
            can be added to this by using the Options -&gt; Customize feature of Visual Studio.&nbsp;
            &nbsp;&nbsp; </li>
    </ul>
    <h3>
        Installation</h3>
    <p>
        See the <a href="#InstallUninstall">Install/Uninstall</a> section below.
    </p>
   
        <h3> <a id="CodeHyperlinking"> Code Hyperlinking </a> </h3>
    <p>
        Visual Studio already had support for embedding web links (eg <a href="http://www.msn.com">
            http://www.msn.com</a>) in the comments of code.&nbsp; You follow a hyperlink
        by pressing the Ctrl' key and pressing the left mouse button. This
        is already very useful for allowing you to references to algorithms (think wikipedia), specifications,
        or anything else that had a URL. &nbsp; However it is also very useful to embed links from one portion
        of the code to another. &nbsp;&nbsp; The HyperAddin add this
        capability by adding <span style="text-decoration: underline"><em>&nbsp;code</em></span>:
        URLs.&nbsp; .
    </p>
    <ul>
        <li>You can refer to a function or type (or any other symbol), but using <span style="text-decoration: underline">
            <span style="color: #0033ff">code:<strong>name</strong></span></span>.&nbsp;
            For example </li>
    </ul>
    <pre>        // In this comment I wanted to talk about the <span style="color: #0033ff; text-decoration: underline">code:MethodTable::Unbox</span> method.
	// By Adding a <span style="color: #3333ff; text-decoration: underline">code:</span> hyperlink, readers can quickly navigate to it.  Any name
	// that can be found using the Edit.FindSymbol (Alt-F12) can be used.  If you
	// need to refer to an overloaded method, it is best to use an anchor (see below).</pre>
    <ul>
        <li>You can generate your own URL anchors by simply putting #<strong>name</strong> in
            the comment somewhere. For example. </li>
    </ul>
    <pre>        // #mytopic
        //
        // ...
        // Somewhere else in the file you can refer to <span style="text-decoration: underline"><span><span style="color: #0033ff">code:#mytopic</span></span></span>.  Now readers
	// can quickly navigate to the #mytopic anchor.  </pre>
    <ul>
        <li>Without further qualification, # anchors only work within a single &nbsp;file. If you wish to refer to an anchor
            outside the current file (a common case), then you need to specify some programming symbol that is in the same file as your anchor.
            &nbsp;For example:</li></ul>
    <pre>        // I need to refer to #mytopic but it is not in the current file.  But I
	// know that this anchor is related to the class 'MethodTable' and thus will
	// be in the same file as that class definition by using <span style="color: #0033ff;
        text-decoration: underline">code:MethodTable#mytopic
</span> 	// I can refer to #mytopic anywhere in any code within the solution.</pre>
    <h4>
        What about overloading?</h4>
    <p>
        There is an obvious problem if you have overloaded method names.&nbsp; The question
        is 'which one does the <span style="color: #0033ff; text-decoration: underline">code:</span>
        hyperlink go to?&nbsp; The answer is 'the first&nbsp; one'.&nbsp; Effectively it
        is arbitrary. &nbsp; Now often this is not an issue because all the different instances
        of the overloaded methods are semantically very similar and tend to call one another,
        so a few F12 (goto definition) will allow the user to navigate to the one that does
        the real work. &nbsp;&nbsp; However when you need to refer to a specific instance
        you can use the # anchors to go to a very specific overload.&nbsp;</p>
    <h4>
        File: Hyperlinks</h4>
    <p>
        The <span style="color: #0033ff; text-decoration: underline">code:</span> hyperlinks a simple but powerful feature for making your code much more
        readable.&nbsp; Sometimes, however you want to create a diagram, or using formatting
        that is very inconvenient
        to create with simple text. &nbsp; For that the obvious
        solution is to create the document in some other tool (say Word, or OneNote), and
        then refer to it using a hyperlink in your code. &nbsp; Unfortunately, in Visual Studio the<strong> file:</strong>
        URL does not work for relative file paths, so the HyperAddin fixed this.&nbsp; &nbsp;For
        example:</p>
    <pre>&nbsp; &nbsp; &nbsp; &nbsp; // I created a very nice block diagram quickly and easily using Viso, and saved
	// The file as 'classDiagram.vsd' in the same directory as this current file.
	// I can refer to it by <span style="color: #0033ff; text-decoration: underline">file:.\classDiagram.vsd</span> and allow readers to quickly open it.
        // As in HTML, relative paths are relative to the file that made the reference.   

<br />	// The file: url also works with # anchors for text<span style="font-size: 12pt;
    font-family: Times New Roman">(source)</span> files.   For example if you 
	// use by <span style="color: #0033ff; text-decoration: underline">file:.\someSourceFile.cs#myTopic</span> and allow you to refer to the #myTopic 
	// anchor in someSourceFile.cs.   If you are certain that you will not move the
	// #myTopic anchor out of this file, and that the file will always stay in the
	// same relative place, you can use this way of referring to it.  Generally however
	// it is better to use code: anchors for this because the # anchors move with the
	// data structure they describe.  </pre>
    
        <h3><a id="GoOut">
            Go Out Navigation (Ctrl+,) (Control Comma) </a>
        </h3>
    <p>
        Code hyperlinks significantly help readers find comments and related code that will
        help them understand the code they are reading.&nbsp; However they do require that
        the writer have the forethought to write the code: hyperlinks. &nbsp; The 'Go Out'
        command is an attempt to do useful navigation without requiring explicit hyperlinks.&nbsp;
        The basic idea, is that when a reader is reading code, there are three natural places
        for the writer of the code to put 'big picture' comments.&nbsp;
    </p>
    <ul>
        <li>At the top of the current method (which should describe the local goal of the code
            currently being read).</li>
        <li>At the top of the current class (which should describe the purpose and invariants
            of that class)</li>
        <li>At the top of the file (which should describe the whole subsystem that is defined
            in the file). </li>
    </ul>
    <p>
        The 'Go Out' command (Ctrl+Comma), supports this navigating to these places quckly.&nbsp;
    </p>
    <ul>
        <li>If you are in a method body, it jumps to the top of the method </li>
        <li>If you are already at the top of a method, it jumps to the top of the class (if
            it has one). </li>
        <li>If you are already at the top of the class, it jumps to the top of the file. </li>
    </ul>
    <p>
        This functionality gives you a very simple procedure to find useful comments. Simply
        hit (Ctrl+,) one or more times.&nbsp; Obviously this is only useful if the writer
        of code put good comments at these locations. &nbsp;
        Note that the Ctrl+- (Ctrl+Minus)
        is useful for getting back to where you where after you have used the Go Out command</p>
    <h3>
        Tips on hyperlink usage</h3>
        <p>
            A code base should have a 'table of contents'.&nbsp; The natural place for this
            is the top of the file that has the Main() method (because GoOut on Main() will
            naturally go there).&nbsp; The table of contents should have an anchor <span style="color: #3333ff">
                #TableOfContents</span>, and there should be a <span style="color: #0033ff; text-decoration: underline">
                    code:#TableOfContents</span> link at the top of the Main() method that leads
            to it. &nbsp; The table of contents' main purpose is to provide a set of links to
            the other main parts of the program. &nbsp; This is usually best done by writing
            a paragraph or so about the program as a whole, and the major components, and having
            an outline that lists the hyperlinks to the code for the major components. &nbsp;
        </p>
    <p>
        In general it is useful if the major components of the application are richly interconnected
        with hyperlinks.&nbsp; Usually they should have a back link to the table of contents,
        and any related components. &nbsp;&nbsp; This makes it easy to navigate to related
        code quickly.&nbsp; If there are any specifications associated with the program
        as a whole or any of its pieces, the of course should be linked using <span style="color: #0033ff;
            text-decoration: underline">file: </span>URL hyperlinks. &nbsp; &nbsp;&nbsp;</p>
    <p>
        <span style="color: #0033ff; text-decoration: underline">File: </span>URLs are particular
        useful if you want to put diagrams into your code.&nbsp; Just &nbsp;use a diagram
        editor of your choice that generates output compatible with Internet Explorer, check
        it in alongside the code, and use <span style="color: #0033ff; text-decoration: underline">
            file: </span>URL to refer to it.&nbsp; Readers will then be able to conveniently
        access the diagrams from Visual Studio.&nbsp;
    </p>
    <p>
        You want to make the 'Go Out' command as useful as possible, by putting a hyperlink
        at the top of a file or a class that will link back to the table of contents.&nbsp;
        This way, by simply using the 'Go Out' command anywhere in the code base, a reader
        can find the table of contents, and then navigate from there.
    </p>
    <p>
        Hyperlinks are also very useful during development itself. &nbsp; It is useful for
        class comments to have links to the most important methods, and this mini table
        of contents has the added advantage that it makes navigating to these 'hot spots'
        quick an easy (Go Out -&gt; Go Out -&gt; Click on Hyperlink). &nbsp; Think of them
        as 'permanent' named bookmarks. &nbsp; Thus put them in early, and use them during
        development.&nbsp;
    </p>
    <p>
        The #region and #endregion declarations in C# are very handy for grouping your comments
        into logical sections.&nbsp; These allow comments to be collapsed as a individual
        groups (by default all comments that are not separated by code are collapsed as
        a single group when outlining (Ctrl-M Ctrl-O) is activated.&nbsp; &nbsp;</p>
        <h3>
        <a id="FormattingComments">
            Formatting (word wrapping) for comments
        </a>
        </h3>
    <p>
        Hyperlinks and the 'Go Out' command are all about making it easy for readers to
        find useful comments.&nbsp; This is only helpful, however if writers actually write
        the comments (or more commonly, readers add comments after having to puzzle out
        how a piece of code works). &nbsp; Word Wrapping is all about making it easy to
        write comments. &nbsp; The basic idea, is that you don't need a word processor to
        write reasonably looking comments. &nbsp; You can write very good looking comments
        with just word wrapping and auto-indenting so that you can make paragraphs and bulleted
        lists. &nbsp;
    </p>
    <p>
        By default when the HyperAddin is installed it enables word wrapping and auto-indenting
        inside
        // style comments. What this means is that if you start a // comment and just keep
        typing, when the word wrap margin is hit, the IDE will automatically start a new
        line, // chars, and indentation to continue the line. By default the margin is 110 characters, but you can change it by selecting the 'Set Word Wrap' item on the 'Addin' &nbsp;menu. If you find the word wrapping annoying, you can turn
        it off with the 'Disable Word Wrap' item on the 'Addin' menu.&nbsp; These settings
        are persisted (in the file HyperAddin.dll.config file), so after setting your preference
        here it will persist from session to session.&nbsp;
    </p>
    <p>
        If you hit a newline in a comment block, the IDE assumes that you are continuing
        the comment, and thus inserts the // and indentation necessary for that scenario.
        This can be annoying if you just wanted to create a one line // comment. If you
        hit a return and did NOT want to continue the comment hit Ctrl+Z (undo), and it
        will remove the comment characters. If you hit Ctrl+Z again, it removes all indentation,
        and if you Ctrl+Z again, it undoes the newline.
    </p>
    <p>
        While the 'on the fly' wrapping is useful for creating new comments, when you modify
        existing comments, the word wrapping gets ruined, and needs to be fixed. This is
        what the 'Format Comment' (Alt+C Alt+F) button on the HyperAddin toolbar does. Basically
        it word wraps the entire paragraph using the following rules to distinguish paragraphs.
    </p>
    <ul>
        <li>Blank lines always separate paragraphs. </li>
        <li>Lines that end in : or &gt; will cause a paragraph break. </li>
        <li>Lines that begin with *, # or &lt; will cause a paragraph break (bulleted list or
            XML comments)</li><li>Lines that begin * are assumed to be bulleted lists and wrapped lines are indented
            4 more spaces. </li>
        <li>Lines with no words (alphabetic characters, eg all *** or ----) are assumed to be
            horizontal rules and never wrap.&nbsp; </li>
    </ul>
    <p>
        These rules are relatively simple, but allow quite a bit of flexibility in your
        comments. * makes for bulleted lists, and &lt;&gt; characters support XML style
        comments (eg. if you program in C#).
    </p>
    <p>
        By default the 'Format Comment' command will format the entire comment block that
        the cursor is in. However if a block of text is selected, it will only format lines
        in that selecti</p>
    <p>
        on. Moreover the formatting rules work whether or not the lines begin
        with // or not. Thus you can format /* */ style comments by selecting the body of
        the comment and
        hitting 'Format Comment'. You can even word wrap plain text files by reading
        them into the IDE, selecting all text and hitting 'Format Comment'.
    </p>
    <h3>
        User Defined Commands</h3>
    <p>
        The HyperAddin allows user defined commands to be added to the HyperAddin menu bar.&nbsp;
        While Visual Studio also has this same capability (on the Tools Menu), it is often
        convinient to package the external tools with the Addin, rather than Visual Studio.&nbsp;
        To add new user defined commands you update the HyperAddin.dll.config file. &nbsp;For
        example
        </p>
    <ul>
    <li>
        &nbsp;&nbsp;&lt;UserCommand Name="EchoSolution" ShortCut="Alt+E,Alt+E"&gt;cmd
        /c echo $(SolutionPath)&lt;/UserCommand&gt;&nbsp; </li>
    </ul>
    <p>
        Defines a command called 'EchoSolution' which has a shorcut of typeing Alt+E twice,
        and prints out the solution path to the Addin log.&nbsp;&nbsp; Once you add a new
        command to the file, you have to tell Visual Studio that it should update its IDE
        to display it.&nbsp; You do this with the following command</p>
    <ul>
        <li>start devenv /resetAddin HyperAddin</li>
    </ul>
    <p>
        This tells Visual Studioto ask HyperAddin to redo its GUI from scratch (and the
        new commands will show up).&nbsp;
    </p>
    <p>
        As can be seen in the 'EchoSolution example, the syntax $(variableName) in the command
        line to execute denotes variables that will be
        substituted at the time the command is invoked.&nbsp; The following variables are
        currently defined.</p>
    <ul>
        <li>$(ActiveDocument) - The full path to the active document.</li>
        <li>$(SolutionPath) - The full path to the solution file.</li>
        <li>$(SolutionDir) - The directory of the solution file. </li>
    </ul>
   
      <h3>
          Troubleshooting</h3>
        <p>
            If you have problems with HyperAddin, you can turn on logging to help understand
            the issue.&nbsp; When logging is turned on messages are sent to the output window
            (Ctrl-W O) in a 'Addin Log' pane.&nbsp; It should come up automatically so it should
            be obvious. &nbsp; Whether logging is on or off is also persisted in the HyperAddin.dll.config
            file so you can diagnose startup problems too.&nbsp;
        </p>
    <h3>
    </h3>
    <h3>
        Known Issues</h3>
    <ol>
        <li>Currently the Visual Studio symbol lookup for VB projects does not work properly.&nbsp;
            You can still use file: URLs and # anchors (for within a file), to refer to other
            parts of the code base, however using code symbols does not work for VB projects.&nbsp;
        </li>
        <li>Inactive Visual Studio Menus: &nbsp; Visual Studio has a system where it remembers
            menu items were added by addins, and avoids loading the addin until the menu entries
            are actually activated. &nbsp; While this avoids some startup cost, it can lead
            to menus that are simply wrong (referring to old addins).&nbsp; If you have problems
            with this you can fix it either by running 'devenv /resetAddin VSAddins.HyperAddin'
            which tells it to reset it for the HyperAddin, or by going to Tools -&gt;&nbsp;
            'Import and Export Setting' -&gt; 'Reset All Settings', which starts completely
            over (but also removes any other customization you had). </li>
    </ol>
    <h3>
        <a id="InstallUninstall">Install / Uninstall</a></h3>
    <p>
        To install HyperAddin simply copy all the HyperLink* files from the distribution
        point to your Visual Studio Addins directory.&nbsp; For example</p>
    <ul>
        <li>copy HyperLink* &nbsp;"%HOMEDIRVE%%HOMEPATH%\My Documents\Visual Studio 2005"</li>
    </ul>
    <p>
        If you wish to uninstall HyperAddin.
        </p>
    <ul>
        <li>Exit Visual Studio</li>
        <li>del "%HOMEDIRVE%%HOMEPATH%\My Documents\Visual Studio 2005\Addins\HyperLink*"</li>
        <li>Unfortunately Visual Studio does not remove the GUI objects associted with a removed
            addin.&nbsp; Currently the only way I know of of removing this unwanted GUI elements
            is go to Tools -&gt;&nbsp; 'Import and Export Setting' -&gt;
            'Reset All Settings' (note that this resets all settings).&nbsp; &nbsp; However the left-over GUI elements
            are Benign (they are inactive and simply do nothing), so you can just leave them
            if you have setttings that don't wish to clobber. </li>
    </ul>
</body>
</html>
